<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.9.1"/>
<title>restclient-cpp: Main Page</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { init_search(); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">restclient-cpp
   </div>
   <div id="projectbrief">C++ client for making HTTP/REST requests</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.9.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li class="current"><a href="index.html"><span>Main&#160;Page</span></a></li>
      <li><a href="pages.html"><span>Related&#160;Pages</span></a></li>
      <li><a href="namespaces.html"><span>Namespaces</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">restclient-cpp Documentation</div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a href="https://travis-ci.org/mrtazz/restclient-cpp">![Build Status](https://travis-ci.org/mrtazz/restclient-cpp.svg?branch=master)</a> <a href="https://coveralls.io/github/mrtazz/restclient-cpp?branch=master">![Coverage Status](https://coveralls.io/repos/mrtazz/restclient-cpp/badge.svg?branch=master&amp;service=github)</a> <a href="https://packagecloud.io/mrtazz/restclient-cpp">![Packagecloud](https://img.shields.io/badge/packagecloud-available-brightgreen.svg)</a> <a href="http://code.mrtazz.com/restclient-cpp/ref/">![doxygen](https://img.shields.io/badge/doxygen-reference-blue.svg)</a> <a href="http://opensource.org/licenses/MIT">![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)</a></p>
<h2>About</h2>
<p>This is a simple REST client for C++. It wraps <a href="http://curl.haxx.se/libcurl/">libcurl</a> for HTTP requests.</p>
<h2>Usage</h2>
<p>restclient-cpp provides two ways of interacting with REST endpoints. There is a simple one, which doesn't need you to configure an object to interact with an API. However the simple way doesn't provide a lot of configuration options either. So if you need more than just a simple HTTP call, you will probably want to check out the advanced usage.</p>
<h3>Simple Usage</h3>
<p>The simple API is just some static methods modeled after the most common HTTP verbs:</p>
<p>```cpp #include "restclient-cpp/restclient.h"</p>
<p><a class="el" href="struct_rest_client_1_1_response.html" title="This structure represents the HTTP response data. ">RestClient::Response</a> r = <a class="el" href="namespace_rest_client.html#a4b542b597eb854401c02520af258006f" title="HTTP GET method. ">RestClient::get</a>("http://url.com") <a class="el" href="struct_rest_client_1_1_response.html" title="This structure represents the HTTP response data. ">RestClient::Response</a> r = <a class="el" href="namespace_rest_client.html#a7de7aa2d333b6e7c5f2c2726d4e5485e" title="HTTP POST method. ">RestClient::post</a>("http://url.com/post", "text/json", "{\"foo": "bla"}")
RestClient::Response r = RestClient::put("<a href="http://url.com/put">http://url.com/put</a>", "text/json", "{"foo": "bla"}")
RestClient::Response r = RestClient::del("<a href="http://url.com/delete">http://url.com/delete</a>")
RestClient::Response r = RestClient::head("<a href="http://url.com">http://url.com</a>") ```</p>
<p>The response is of type <a href="http://code.mrtazz.com/restclient-cpp/ref/struct_rest_client_1_1_response.html">RestClient::Response</a> and has three attributes:</p>
<p>```cpp <a class="el" href="struct_rest_client_1_1_response.html#a3b3b63aeae7ca761d54a009ee329ea28">RestClient::Response.code</a> // HTTP response code <a class="el" href="struct_rest_client_1_1_response.html#a87ba6d5e5ae9ae7d628d5ed34b36cc95">RestClient::Response.body</a> // HTTP response body <a class="el" href="struct_rest_client_1_1_response.html#a2141b4d9929e0df26d918dfba8451496">RestClient::Response.headers</a> // HTTP response headers ```</p>
<h3>Advanced Usage</h3>
<p>However if you want more sophisticated features like connection reuse, timeouts or authentication, there is also a different, more configurable way.</p>
<p>```cpp #include "restclient-cpp/connection.h" #include "restclient-cpp/restclient.h"</p>
<p>// initialize <a class="el" href="namespace_rest_client.html" title="namespace for all RestClient definitions ">RestClient</a> <a class="el" href="namespace_rest_client.html#a38395626a68f2dc66e2acf5b01f5b70b" title="global init function. Call this before you start any threads. ">RestClient::init()</a>;</p>
<p>// get a connection object <a class="el" href="class_rest_client_1_1_connection.html" title="Connection object for advanced usage. ">RestClient::Connection</a>* conn = new <a class="el" href="class_rest_client_1_1_connection.html" title="Connection object for advanced usage. ">RestClient::Connection</a>("http://url.com");</p>
<p>// configure basic auth conn-&gt;SetBasicAuth("WarMachine68", "WARMACHINEROX");</p>
<p>// set connection timeout to 5s conn-&gt;SetTimeout(5);</p>
<p>// set custom user agent // (this will result in the UA "foo/cool restclient-cpp/VERSION") conn-&gt;SetUserAgent("foo/cool");</p>
<p>// enable following of redirects (default is off) conn-&gt;FollowRedirects(true);</p>
<p>// set headers <a class="el" href="namespace_rest_client.html#ab2bbc7fd5ec10171e4e1fb2d7fc8e865">RestClient::HeaderFields</a> headers; headers["Accept"] = "application/json"; conn-&gt;SetHeaders(headers)</p>
<p>// append additional headers conn-&gt;AppendHeader("X-MY-HEADER", "foo")</p>
<p>// if using a non-standard Certificate Authority (CA) trust file conn-&gt;SetCAInfoFilePath("/etc/custom-ca.crt")</p>
<p><a class="el" href="struct_rest_client_1_1_response.html" title="This structure represents the HTTP response data. ">RestClient::Response</a> r = conn-&gt;get("/get") <a class="el" href="struct_rest_client_1_1_response.html" title="This structure represents the HTTP response data. ">RestClient::Response</a> r = conn-&gt;head("/get") <a class="el" href="struct_rest_client_1_1_response.html" title="This structure represents the HTTP response data. ">RestClient::Response</a> r = conn-&gt;del("/delete")</p>
<p>// set different content header for POST and PUT conn-&gt;AppendHeader("Content-Type", "text/json") <a class="el" href="struct_rest_client_1_1_response.html" title="This structure represents the HTTP response data. ">RestClient::Response</a> r = conn-&gt;post("/post", "{\"foo": "bla"}")
RestClient::Response r = conn-&gt;put("/put", "text/json", "{"foo": "bla"}")</p>
<p>// deinit <a class="el" href="namespace_rest_client.html" title="namespace for all RestClient definitions ">RestClient</a>. After calling this you have to call <a class="el" href="namespace_rest_client.html#a38395626a68f2dc66e2acf5b01f5b70b" title="global init function. Call this before you start any threads. ">RestClient::init()</a> // again before you can use it <a class="el" href="namespace_rest_client.html#aa4dc1337561e6622b013d22639d3d26c" title="global disable function. Call this before you terminate your program. ">RestClient::disable()</a>; ```</p>
<p>The responses are again of type <a href="http://code.mrtazz.com/restclient-cpp/ref/struct_rest_client_1_1_response.html">RestClient::Response</a> and have three attributes:</p>
<p>```cpp <a class="el" href="struct_rest_client_1_1_response.html#a3b3b63aeae7ca761d54a009ee329ea28">RestClient::Response.code</a> // HTTP response code <a class="el" href="struct_rest_client_1_1_response.html#a87ba6d5e5ae9ae7d628d5ed34b36cc95">RestClient::Response.body</a> // HTTP response body <a class="el" href="struct_rest_client_1_1_response.html#a2141b4d9929e0df26d918dfba8451496">RestClient::Response.headers</a> // HTTP response headers ```</p>
<p>The connection object also provides a simple way to get some diagnostics and metrics information via <code>conn-&gt;GetInfo()</code>. The result is a <code><a class="el" href="struct_rest_client_1_1_connection_1_1_info.html" title="holds some diagnostics information about the connection object it came from ">RestClient::Connection::Info</a></code> struct and looks like this:</p>
<p>```cpp typedef struct { std::string base_url; RestClients::HeaderFields headers; int timeout; struct { std::string username; std::string password; } basicAuth;</p>
<p>std::string certPath; std::string certType; std::string keyPath; std::string customUserAgent; struct { // total time of the last request in seconds Total time of previous // transfer. See CURLINFO_TOTAL_TIME int totalTime; // time spent in DNS lookup in seconds Time from start until name // resolving completed. See CURLINFO_NAMELOOKUP_TIME int nameLookupTime; // time it took until Time from start until remote host or proxy // completed. See CURLINFO_CONNECT_TIME int connectTime; // Time from start until SSL/SSH handshake completed. See // CURLINFO_APPCONNECT_TIME int appConnectTime; // Time from start until just before the transfer begins. See // CURLINFO_PRETRANSFER_TIME int preTransferTime; // Time from start until just when the first byte is received. See // CURLINFO_STARTTRANSFER_TIME int startTransferTime; // Time taken for all redirect steps before the final transfer. See // CURLINFO_REDIRECT_TIME int redirectTime; // number of redirects followed. See CURLINFO_REDIRECT_COUNT int redirectCount; } lastRequest; } Info; ```</p>
<h4>Persistent connections/Keep-Alive</h4>
<p>The connection object stores the curl easy handle in an instance variable and uses that for the lifetime of the object. This means curl will <a href="http://curl.haxx.se/docs/faq.html#What_about_Keep_Alive_or_persist">automatically reuse connections</a> made with that handle.</p>
<h2>Thread Safety</h2>
<p>restclient-cpp leans heavily on libcurl as it aims to provide a thin wrapper around it. This means it adheres to the basic level of thread safety <a href="http://curl.haxx.se/libcurl/c/threadsafe.html">provided by libcurl</a>. The <code><a class="el" href="namespace_rest_client.html#a38395626a68f2dc66e2acf5b01f5b70b" title="global init function. Call this before you start any threads. ">RestClient::init()</a></code> and <code><a class="el" href="namespace_rest_client.html#aa4dc1337561e6622b013d22639d3d26c" title="global disable function. Call this before you terminate your program. ">RestClient::disable()</a></code> methods basically correspond to <code>curl_global_init</code> and <code>curl_global_cleanup</code> and thus need to be called right at the beginning of your program and before shutdown respectively. These set up the environment and are <b>not thread-safe</b>. After that you can create connection objects in your threads. Do not share connection objects across threads as this would mean accessing curl handles from multiple threads at the same time which is not allowed.</p>
<p>In order to provide an easy to use API, the simple usage via the static methods implicitly calls the curl global functions and is therefore also <b>not thread-safe</b>.</p>
<h2>HTTPS User Certificate</h2>
<p>Simple wrapper functions are provided to allow clients to authenticate using certificates. Under the hood these wrappers set cURL options, e.g. <code>CURLOPT_SSLCERT</code>, using <code>curl_easy_setopt</code>. Note: currently <code>libcurl</code> compiled with <code>gnutls</code> (e.g. <code>libcurl4-gnutls-dev</code> on ubuntu) is buggy in that it returns a wrong error code when these options are set to invalid values.</p>
<p>```cpp // set CURLOPT_SSLCERT conn-&gt;SetCertPath(certPath); // set CURLOPT_SSLCERTTYPE conn-&gt;SetCertType(type); // set CURLOPT_SSLKEY conn-&gt;SetKeyPath(keyPath); ```</p>
<h2>Dependencies</h2>
<ul>
<li><a href="http://curl.haxx.se/libcurl/">libcurl</a></li>
</ul>
<h2>Installation</h2>
<p>There are some packages available for Linux on <a href="https://packagecloud.io/mrtazz/restclient-cpp">packagecloud</a>. And for OSX you can get it from the mrtazz/oss homebrew tap:</p>
<p>```bash brew tap mrtazz/oss brew install restclient-cpp ```</p>
<p>Otherwise you can do the regular autotools dance:</p>
<p>```bash ./autogen.sh ./configure make install ```</p>
<h2>Contribute</h2>
<p>All contributions are highly appreciated. This includes filing issues, updating documentation and writing code. Please take a look at the https://github.com/mrtazz/restclient-cpp/blob/master/CONTRIBUTING.md "contributing guidelines" before so your contribution can be merged as fast as possible. </p>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Fri Dec 2 2016 10:53:09 for restclient-cpp by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.9.1
</small></address>
</body>
</html>
